feat(harness): support monorepo workspace topology - #21
Draft
phodal wants to merge 2 commits into
Draft
Conversation
Introduce a frozen workspace-topology contract and thread package scope through evidence collection, provider sessions, inherited assets, findings, rendering, and repair routing. Implements docs/specs/2026-07-25-monorepo-workspace-support.md. The change keeps legacy findings readable, fails closed on incomplete or cross-package ownership, and was validated with npm test, npm run pack:verify, direct doc-link checks, and preview endpoint smoke tests.
There was a problem hiding this comment.
Pull request overview
This PR introduces a versioned, Git-aware workspace topology (repo-root / workspace-member / repo-subtree / standalone) and threads that frozen topology + path-scoped analysis contract through evidence bundling, session providers, report rendering, and finding repair/record flows so monorepo targets and owners are explicit end-to-end.
Changes:
- Add
scripts/workspace-topology/*(contract, inventory + manifest discovery, target validation, CLI) to resolve and freeze topology + analysis scope. - Introduce structured
finding.target(contract v26) with validation and fail-closed owner/package routing across projection, rendering, and fix-output recording. - Update session providers + core-change-watch to support topology-scoped session/workspace qualification and path-scoped Git analysis.
Reviewed changes
Copilot reviewed 68 out of 68 changed files in this pull request and generated 2 comments.
Show a summary per file
| File | Description |
|---|---|
| test/task-loop-source.test.mjs | Updates practice coverage expectations to include inherited Skills. |
| test/task-loop-report.test.mjs | Bumps report contract assertions to v26 and adds structured target / owner routing tests. |
| test/session-workspace-match.test.mjs | Adds coverage for workspace match topology validation and privacy-safe diagnostics (incl. Windows paths). |
| test/scripts-refactor-contract.test.mjs | Updates frozen CLI output SHA256 expectations. |
| test/plugin-manifests.test.mjs | Ensures workspace-topology scripts are present in npm packaging manifest verification. |
| test/maturity-models.test.mjs | Aligns maturity model constants with new report contract v26 + target contract constant. |
| test/host-plugin-artifact.test.mjs | Ensures runtime bundle includes workspace-topology scripts. |
| test/harness-report-render-cli.test.mjs | Adds render CLI tests for legacy vs v26 findings and structured target enforcement. |
| test/harness-findings-repair.test.mjs | Verifies repairs preserve valid structured finding targets. |
| test/harness-canvas-validation.test.mjs | Ensures installed-like Canvas validation includes workspace-topology scripts. |
| test/fixtures/scripts-refactor-contract/root-help.txt | Updates CLI help fixture to include workspace-topology subcommand. |
| test/fixtures/scripts-refactor-contract/harness-help.txt | Updates harness subcommand help fixture and examples for topology command. |
| test/better-harness-skill.test.mjs | Asserts skill docs mention frozen topology target fields and provider agreement requirements. |
| test/better-harness-evidence-bundle.test.mjs | Bumps evidence bundle schema to v2 and adds tests for one-shot topology resolution + failure modes. |
| test/better-harness-cli.test.mjs | Verifies CLI command inventory exposes workspace-topology and handles spaced paths. |
| test/agent-lint-monorepo.test.mjs | Adds monorepo fixtures validating topology-backed agent instruction discovery and scoping. |
| test/agent-asset-baseline.test.mjs | Updates baseline expectations for truncation/partial status and inherited owner routing in monorepos. |
| skills/better-harness/SKILL.md | Updates guidance to require reading frozen topology target fields before delegation. |
| skills/better-harness/references/finding-bound-fix.md | Adds explicit topology binding rules and structured target fail-closed requirements for repairs. |
| scripts/workspace-topology/manifests.mjs | Implements manifest- and convention-based member + instruction-scope discovery with safety checks. |
| scripts/workspace-topology/inventory.mjs | Adds bounded Git + filesystem fallback inventory collection for topology discovery. |
| scripts/workspace-topology/index.mjs | Adds topology resolver, analysis scope derivation, and exports for finding targets. |
| scripts/workspace-topology/finding-target.mjs | Defines/validates structured finding targets against frozen topology. |
| scripts/workspace-topology/contract.mjs | Defines workspace topology schema, route normalization/containment, and freezing/validation helpers. |
| scripts/workspace-topology/cli.mjs | Adds workspace-topology CLI entrypoint (text/json output). |
| scripts/session-analysis/platforms/cursor.mjs | Adds workspace CWD candidate binding + topology-aware preflight/truncation behavior. |
| scripts/session-analysis/platforms/codex.mjs | Adds topology-aware workspace qualification/hydration and marks read coverage/truncation. |
| scripts/session-analysis/platforms/claude.mjs | Adds topology-aware transcript probing, CWD candidate binding, and read preflight coverage. |
| scripts/npm-package/verify-pack.mjs | Requires workspace-topology scripts in packed artifacts and runtime bundles. |
| scripts/harness-analysis/validate-canvas.mjs | Validates structured finding.target and expands practice scopes to include Inherited. |
| scripts/harness-analysis/task-loop-source.mjs | Threads analysisScope/topology through scanning and adds default findingTarget from topology. |
| scripts/harness-analysis/task-loop-repository-evidence.mjs | Makes repo evidence scanning respect analysis scopes and handle non-git/standalone topologies. |
| scripts/harness-analysis/task-loop-report.mjs | Adds target to findings contract, projects fallback target, and validates finding targets. |
| scripts/harness-analysis/report-source/source.mjs | Validates repositoryEvidence.findingTarget in report source schema. |
| scripts/harness-analysis/report-run.mjs | Passes topology + analysisScope into report-source generation. |
| scripts/harness-analysis/report-data-schema.mjs | Validates finding targets during report normalization/render based on topology + v26 threshold. |
| scripts/harness-analysis/repair-findings-json.mjs | Updates repair normalization to include target and to prefer ownerRoute when inferring target paths. |
| scripts/harness-analysis/renderers/better-harness.mjs | Permits/validates target in findings consumed by Better Harness renderer. |
| scripts/harness-analysis/render-report.mjs | Resolves topology for render target and enforces structured target requirements for v26/package workspaces. |
| scripts/harness-analysis/record-fix-output.mjs | Adds topology-bound validation so fix-output can’t target sibling/out-of-owner paths. |
| scripts/harness-analysis/practice-findings.mjs | Adds topology-aware grouping and structured targets for practice findings with owner routing. |
| scripts/harness-analysis/learning-capture-evidence.mjs | Scopes git log collection to analysisScope pathspecs and filters commit file lists accordingly. |
| scripts/harness-analysis/fluency-dimensions.mjs | Introduces FINDING_TARGET_REPORT_CONTRACT_VERSION and sets report contract to v26. |
| scripts/harness-analysis/evidence-bundle/session-evidence.mjs | Passes frozen topology + analysisScope into session evidence collection. |
| scripts/harness-analysis/evidence-bundle/project-harness.mjs | Runs project harness evidence with topology/analysis scope (and returns partial when evidence pack is non-ok). |
| scripts/harness-analysis/evidence-bundle/index.mjs | Resolves topology once, freezes it into context, and fails/partials bundles when topology is incomplete. |
| scripts/harness-analysis/evidence-bundle/contract.mjs | Bumps schema to v2 and enforces workspace/topology/analysis-scope binding invariants. |
| scripts/harness-analysis/evidence-bundle/agent-customize.mjs | Passes topology + analysisScope into agent customization evidence collection. |
| scripts/core-change-watch/project-profile.mjs | Makes project profiling analysis-scope aware and exports analysisScope in results. |
| scripts/core-change-watch/git-history-profile.mjs | Makes history profiling analysis-scope aware and handles unborn repos as empty history. |
| scripts/core-change-watch/evidence-pack.mjs | Threads analysisScope through all evidence-pack sub-analyses and source command strings. |
| scripts/core-change-watch/diff-impact.mjs | Scopes diff impact analysis to analysisScope and adds compatibility checks. |
| scripts/core-change-watch/core-candidates.mjs | Scopes core-candidate detection to analysisScope and normalizes paths accordingly. |
| scripts/core-change-watch/common.mjs | Introduces structured analysisScope helpers and makes Git failures explicit (typed errors). |
| scripts/core-change-watch/change-drift.mjs | Scopes drift analysis + companion candidate discovery to analysisScope pathspecs. |
| scripts/coding-agent-practices/inventory.mjs | Adds inherited surfaces and routes origin metadata into practice coverage rows. |
| scripts/coding-agent-practices/asset-baseline.mjs | Adds inherited inventory merging, truncation reporting, and partial status when envelopes truncate. |
| scripts/better-harness-cli/registry.mjs | Registers harness workspace-topology subcommand in the CLI registry. |
| scripts/better-harness-cli/cli.mjs | Adds workspace-topology example to group examples. |
| scripts/agent-lint/index.mjs | Adds topology-backed entrypoint discovery and populates package/owner routes on findings. |
| scripts/agent-customize/core/items.mjs | Allows inherited sources for project/workspace scope kinds. |
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Comment on lines
+337
to
+345
| if (options.target && topology) { | ||
| const requestedTarget = await realpath(path.resolve(options.target)); | ||
| const topologyTarget = path.resolve(topology.requestedWorkspace); | ||
| if (requestedTarget !== topologyTarget) { | ||
| throw Object.assign(new Error("--target does not match the frozen workspace topology"), { | ||
| code: "RENDER_WORKSPACE_TOPOLOGY_MISMATCH", | ||
| }); | ||
| } | ||
| } |
Comment on lines
+28
to
+37
| const body = arg.slice(2); | ||
| const equal = body.indexOf("="); | ||
| if (equal !== -1) { | ||
| options[body.slice(0, equal)] = body.slice(equal + 1); | ||
| continue; | ||
| } | ||
| if (body === "json" || body === "help") { | ||
| options[body] = true; | ||
| continue; | ||
| } |
Canonicalize both sides of filesystem identity checks so symlink, case, and Windows 8.3 path aliases do not escape package scope or reject a valid render target. Parse explicit topology CLI boolean values strictly instead of relying on string truthiness. Updates docs/specs/2026-07-25-monorepo-workspace-support.md with AC13. The focused regressions passed 102/102, the full suite passed 926/926, and pack, doc-link, and preview smoke checks passed. Co-authored-by: Codex (GPT 5.6 Sol) <codex@openai.com>
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
What changed
Why
Flat-workspace assumptions could omit inherited instructions, widen package evidence to sibling packages, misattribute root-CWD sessions, or route a finding repair to the wrong owner. This change makes target identity and evidence coverage explicit from collection through repair.
Impact
One bundle still analyzes one target, but repository-root, workspace-member, repository-subtree, and standalone identities are now explicit. New package findings use report contract v26; report contracts 1-25 remain readable.
Traceability
docs/specs/2026-07-25-monorepo-workspace-support.mdValidation
npm test— 924/924npm run pack:verify— npm 316 entries, runtime zip 342 entriesnode --test test/doc-link-graph.test.mjs test/better-harness-skill.test.mjs— 18/18/healthreturnedok;/canvas-module.jsreturned the transformed report modulegit diff --checkRisk and rollback
Key risks are package-scope widening, root-session contamination, path traversal, and incomplete coverage claims. Tests cover cross-package and partial topology cases, symlink escape, special-character routes, all session providers, legacy finding rendering, and large-session hydration. Revert commit
6040d40to restore the previous flat-workspace behavior.